home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / ftnchop.z / ftnchop
Text File  |  1998-10-30  |  9KB  |  179 lines
  1. FTNCHOP(1)                                            Last changed: 7-23-97
  2.  
  3.  
  4. NNAAMMEE
  5.      ffttnncchhoopp - Invokes the program unit problem isolator
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ffttnncchhoopp [--GG] [--BB] [--gg _g_d_i_r] [--bb _d_i_r] [--rr] [--vv] [--VV] LLIISSTT
  9.  
  10. IIMMPPLLEEMMEENNTTAATTIIOONN
  11.      UNICOS, UNICOS/mk, and IRIX systems
  12.  
  13. DDEESSCCRRIIPPTTIIOONN
  14.      The ffttnncchhoopp utility is a program that isolates problems to object file
  15.      level by using a mix-and-match technique.  This utility is most useful
  16.      with programs that contain several source files.  To run the ffttnncchhoopp
  17.      utility you need to have one working version of a program and one
  18.      version that is not working.  When run, ffttnncchhoopp finds the object files
  19.      that are causing the program to malfunction.  Debugging efforts can
  20.      then be concentrated to those files.
  21.  
  22.      The ffttnncchhoopp utility works by selecting object files from two
  23.      directories _g_d_i_r and _b_d_i_r, whose default names are GGOOOODD and BBAADD.  It
  24.      reads the list of object files from file LLIISSTT, one file name per line
  25.      with no trailing blanks.  To make a trial run, ffttnncchhoopp prefixes object
  26.      file names with _g_d_i_r// or _b_d_i_r// and writes them to a file named
  27.      FFTTNNCCHHOOPP__LLIISSTT.  It then executes the program or shell script named
  28.      FFTTNNCCHHOOPP__TTEESSTT.  This program or shell script links the program by using
  29.      the list in FFTTNNCCHHOOPP__LLIISSTT, tests it, and returns an exit status of zero
  30.      if the test passed and a non-zero exit status if the test failed.
  31.      Depending on the return value, ffttnncchhoopp will change the list and call
  32.      FFTTNNCCHHOOPP__TTEESSTT again until it has found one file in _b_d_i_r that is causing
  33.      the failure.  At this point ffttnncchhoopp will run another test to determine
  34.      if that was the only bad file.  If not, ffttnncchhoopp will repeat the test
  35.      process with the remaining files until all bad files are found.
  36.  
  37.      Before doing any mixing, ffttnncchhoopp checks the boundary conditions by
  38.      making one run with all good files and another run with all bad files.
  39.      These checks can be skipped if you specify the --GG and --BB options,
  40.      respectively.  If these checks are skipped and the boundary conditions
  41.      are not correct, that is if the program with all good files fails or
  42.      if the program with all bad files passes, ffttnncchhoopp can return
  43.      inaccurate information.
  44.  
  45.      The ffttnncchhoopp command accepts the following options:
  46.  
  47.      --GG               Specifies that ffttnncchhoopp skip checking boundry
  48.                       conditions on good files.
  49.  
  50.      --BB               Specifies that ffttnncchhoopp skip checking boundry
  51.                       conditions on bad files.
  52.  
  53.      --gg _g_d_i_r          Specifies name of directory containing the good
  54.                       files.  Default is GGOOOODD.
  55.  
  56.      --bb _g_d_i_r          Specifies name of directory containing the bad files.
  57.                       Default is BBAADD.
  58.  
  59.      --rr               Restarts ffttnncchhoopp from the point where the test run
  60.                       was aborted.  Must be the only option on the command
  61.                       line.
  62.  
  63.      --vv               Specifies that the entire contents of FFTTNNCCHHOOPP__LLIISSTT is
  64.                       printed.  Default is to print a single line that
  65.                       lists the name of the bad file.
  66.  
  67.      --VV               Displays version, date, and time of the ffttnncchhoopp
  68.                       executable running on your system.  If this is the
  69.                       only option specified on the command line, the
  70.                       utility exits after printing the information; the
  71.                       tool itself is not started.
  72.  
  73. NNOOTTEESS
  74.      Depending on the number of files and the length of the test run,
  75.      ffttnncchhoopp can take several hours to complete.
  76.  
  77.      All object files and test files must remain unmodified during the
  78.      entire run.  The test script must be written carefully so that it does
  79.      not depend on any previous run in any way.
  80.  
  81.      By default ffttnncchhoopp prints just one message line for each bad file
  82.      found:
  83.  
  84.           ##### FOUND BAD FILE _f_i_l_e
  85.  
  86.      It is advisable to print the contents of FFTTNNCCHHOOPP__LLIISSTT to keep a record
  87.      of the entire run.
  88.  
  89.      The ffttnncchhoopp utility makes no distinction between a test failure and a
  90.      script failure.  If the script FFTTNNCCHHOOPP__TTEESSTT has a syntax error, or if
  91.      the ff9900 comand fails for any reason, ffttnncchhoopp assumes a test failure.
  92.  
  93.      If the --GG switch is not specified, the utility stops as soon as it
  94.      finds the all-good file test failing. Otherwise it will find all the
  95.      files to be bad and return inaccurate information.  Therefore, it is
  96.      advisable to watch the starting of a ffttnncchhoopp run to make sure it is
  97.      progressing correctly.
  98.  
  99.      While ffttnncchhoopp is running a test, it writes state information to a file
  100.      called FFTTNNCCHHOOPP__SSTTAATT.  If a run aborts for any reason, you can restart
  101.      ffttnncchhoopp from that point by entering the following command:
  102.  
  103.           ftnchop -r
  104.  
  105.      This causes ffttnncchhoopp to read state information from FFTTNNCCHHOOPP__SSTTAATT.  This
  106.      state information includes the names of the good and bad directories
  107.      and all the options.
  108.  
  109.      ffttnncchhoopp does not require that files be object files.
  110.  
  111. EEXXAAMMPPLLEESS
  112.      A typical situation occurs when a large program made of several object
  113.      files works when compiled without optimization but not when compiled
  114.      with optimization.  To use ffttnncchhoopp to locate the problem, create two
  115.      directories, for example OO00 and OO22.  Keep all unoptimized object files
  116.      in directory OO00 and optimized files in directory OO22.  Then create an
  117.      automated method of determining the success of a program test run.
  118.      One way would be to create a shell script named FFTTNNCCHHOOPP__TTEESSTT that
  119.      causes the program to print TTEESSTT PPAASSSSEEDD at the end of a successful run
  120.      but return a message of TTEESSTT FFAAIILLEEDD upon an unsuccessful run. The
  121.      shell script would look like the following script:
  122.  
  123.           echo ================= TESTING WITH: ==================
  124.           cat FTNCHOP_LIST
  125.           f77 -o prog `cat FTNCHOP_LIST`
  126.           prog > RESULT
  127.           tail -l RESULT > t1
  128.           if grep t1 'RUN COMPLETED'
  129.           then
  130.                   echo   TEST PASSED
  131.                   exit 0
  132.           else
  133.                   echo TEST FAILED
  134.                   exit 1
  135.           fi
  136.      Make sure the script has executable permission.  Make a file
  137.      containing the names of all constituent files, one per line, by using
  138.      the following format:
  139.  
  140.           /bin/ls O0 > OLIST
  141.  
  142.      The execute the ffttnncchhoopp command as follows:
  143.  
  144.           ftnchop -gO0 -bO2 OLIST > FTNCHOP.RES
  145.      After the run is complete, enter the following ggrreepp command to find
  146.      the bad files:
  147.  
  148.           grep FOUND FTNCHOP.RES
  149.  
  150.      Another example of failure can occur when a program gets an exception
  151.      error and dumps core memory.  In this case the test that a failure
  152.      occurred may be the existence of a core file, as shown in the
  153.      following example:
  154.  
  155.           rm -f core   # _r_e_m_o_v_e _f_r_o_m _a_n_y _p_r_e_v_i_o_u_s _r_u_n_s
  156.           prog > RESULT
  157.           if test -f core
  158.           then
  159.                   exit 1
  160.           else
  161.                   exit 0
  162.           fi
  163.  
  164. FFIILLEESS
  165.      BBAADD                      Default name of the directory containing the
  166.                               "bad" files.
  167.  
  168.      GGOOOODD                     Default name of the directory containing the
  169.                               "good" files.
  170.  
  171.      FFTTNNCCHHOOPP__LLIISSTT             List of files to be tested by ffttnncchhoopp.
  172.  
  173.      FFTTNNCCHHOOPP__TTEESSTT             Name of test script called by ffttnncchhoopp.
  174.  
  175. SSEEEE AALLSSOO
  176.      ff9900(1) and ffttnnsspplliitt(1)
  177.  
  178.      This man page is available only online.
  179.